home *** CD-ROM | disk | FTP | other *** search
/ CD Ware Multimedia 1995 May / cd Ware (Juegos) Epimundo.iso / DOS / C / BPREAL.ZIP / BPREAL.DOC < prev    next >
Encoding:
Text File  |  1993-04-19  |  11.9 KB  |  254 lines
  1.                              BPREAL
  2.               Borland Pascal Real-Type Conversions
  3.                         by Richard Biffl
  4.  
  5.  
  6.      The accompanying module, BPREAL.C, contains functions in the
  7. C language to convert floating-point numbers between the IEEE
  8. "double" type used by most PC-based C compilers and the
  9. proprietary "real" type used by Borland Pascal.  The functions
  10. allow C programs to read numeric data stored by Borland Pascal
  11. programs, and to write numeric data in a format accessible to
  12. Borland Pascal programs.
  13.  
  14.      Recent versions of Borland Pascal, beginning with Turbo
  15. Pascal 4.0, support the same IEEE-standard floating-point types
  16. used by C (and other) compilers, but the use of IEEE types in
  17. Borland Pascal is optional.  Many Pascal programmers continue to
  18. use Borland's default real type because programs that use it do
  19. not require a numeric coprocessor or coprocessor-emulation code.
  20.  
  21.      Borland Pascal can automatically convert values between real
  22. and IEEE formats, but other languages do not have built-in
  23. support for the real type.  The appropriate IEEE type for real
  24. conversions is the 8-byte double-precision type, called double in
  25. both C and Borland Pascal, which can store any value that can be
  26. stored by a 6-byte real.  The real_to_double function in the
  27. BPREAL module performs this conversion, returning a C double.
  28.  
  29.      BPREAL's double_to_real function performs the opposite
  30. conversion, from C double to Borland Pascal real.  The function
  31. can return an error code to indicate whether the original double
  32. value was accurately converted to the narrower real type.
  33.  
  34.  
  35. The Real and Double Formats
  36.  
  37.      The real and double formats comprise three fields:  a sign
  38. bit, a significand field, and an exponent field.  For the real
  39. type, the fields can be visualized as arranged like this, with
  40. the most significant bit at the left end of each field:
  41.  
  42.             Field:  Sign      Significand    Exponent
  43.      Width (bits):    1            39            8
  44.  
  45. The fields of the IEEE double type are arranged like this:
  46.  
  47.             Field:  Sign      Exponent       Significand
  48.      Width (bits):    1          11               52
  49.  
  50. In a PC's memory, these values are stored with the right-most 8-
  51. bit bytes at the lowest address (or first on a disk), so that the
  52. real's exponent would be stored as the first byte and its sign
  53. bit would be the most significant (leftmost) bit of the sixth
  54. byte.
  55.  
  56.      The sign bit is set when the value is less than 0.0
  57. (negative).  The exponent field (8 bits for real, 11 bits for
  58. double) represents the integer part of the base-2 logarithm of
  59. the value, indicating the value's absolute magnitude.  The
  60. exponent is biased by some value (129 for real, 1023 for double),
  61. so although the binary value of the field is positive, it can
  62. signify a negative value when the bias is subtracted from it. 
  63. The significand field (39 bits for real, 52 bits for double) is
  64. the fractional part by which the value indicated by the exponent
  65. is increased.  Thus, for both types, the represented value is
  66. generally
  67.  
  68.  
  69.     Sign           Significand              (Exponent - Bias)
  70. (-1)      *  (1 + -------------------)  *  2
  71.                     SignificandWidth
  72.                    2
  73.  
  74.  
  75.      There are a few special cases.  The value of a real is 0.0
  76. when the exponent field is 0, i.e., when no bit in the exponent
  77. field is set.  The IEEE double has a value of 0.0 when both the
  78. exponent field and the significand field have values of 0, but
  79. the double's sign bit can be set to represent -0.0 as well as
  80. 0.0.  When all 11 bits are set in the double's exponent field, so
  81. that it has its highest possible value (2047), and none of the
  82. bits in the significand field is set, so that its value is 0, the
  83. double's value is Inf (infinity) or -Inf, depending on the sign
  84. bit.  If the double's exponent field is 2047 and its significand
  85. is not equal to 0, the value is NaN (not a number).
  86.  
  87.      The real's format permits an absolute range of approximately
  88. 2.9e-39 to 1.7e38 (decimal) and a precision of 11-12 significant
  89. decimal digits.  The double's wider format offers an absolute
  90. range of approximately 5.0e-324 to 1.7e308 and a precision of 15-
  91. 16 significant digits.  (The tiniest values represented by
  92. doubles sacrifice precision for their very low magnitude.)
  93.  
  94.  
  95. Conversion Functions
  96.  
  97.      Conversion between a real and a double mainly involves
  98. transferring the bit fields from the source to the target. 
  99. Because there is no high-level access to the bits in a double,
  100. and C has no real type, both double and real must be treated as
  101. arrays, the elements of which can be manipulated individually at
  102. the bit level.  Instead of treating doubles and reals as arrays
  103. of bytes, it is more efficient to treat them as arrays of 16-bit
  104. unsigned ints.  A typedef statement in BPREAL.C declares the
  105. "real" type as an array of 3 unsigned ints, and a "doublearray"
  106. union so that doubles can be handled as arrays of 4 unsigned
  107. ints.
  108.  
  109.      The bits contained in each of the arrays' elements are
  110. listed below.  For each element, its contents are listed from
  111. left to right (most significant bit to least significant), and
  112. bit 1 of each field is the field's most significant bit:
  113.  
  114.           real[2]        Sign 1, Significand 1-15
  115.           real[1]        Significand 16-31
  116.           real[0]        Significand 32-39, Exponent 1-8
  117.  
  118.      doublearray.a[3]    Sign 1, Exponent 1-11, Significand 1-4
  119.      doublearray.a[2]    Significand 5-20
  120.      doublearray.a[1]    Significand 21-36
  121.      doublearray.a[0]    Significand 37-52
  122.  
  123.      Conversion from real to double is straightforward, because
  124. any value that can be represented by a real can be represented by
  125. a double.  The real_to_double function first checks whether the
  126. exponent is 0.  If so, it returns the double 0.0.  Otherwise, it
  127. adds 894 to the exponent because the double's exponent bias
  128. (1023) is 894 greater than the real's bias (129), and it places
  129. the exponent in the correct location in the double (element 3,
  130. shifted 4 bits to the left).  It then moves the sign bit and the
  131. 39-bit significand to their proper locations.
  132.  
  133.      Conversion from double to real is trickier, because the IEEE
  134. type has greater range and precision and more special cases than
  135. the real.  Since error-free conversion is not assured, the
  136. double_to_real function returns an error code of an enumerated
  137. type called prconverr (for Pascal Real Conversion Error).  The
  138. error codes range in increasing seriousness from prOK, which
  139. means no error, to prNaN, which means that the double value was
  140. NaN (not a number), which cannot be represented by a real.
  141.  
  142.      The double_to_real function first checks whether the double
  143. value is 0.0 or -0.0, either of which is converted to a real
  144. representation of 0.0 before returning prOK.
  145.  
  146.      Next, the function checks whether all the bits in the
  147. double's exponent are set.  If they are, the double's value is
  148. either Inf or NaN (or one of their negations).  If the value is
  149. Inf, the real's exponent and significand fields are filled so as
  150. to represent the largest value possible, the sign bit is
  151. transferred, and the code prInf is returned.  If the value is
  152. NaN, a real value of 0.0 and a code of prNaN are returned.
  153.  
  154.      After these tests, the significand is rounded.  The real's
  155. 39-bit significand does not allow as much precision as the
  156. double's 52-bit significand.  To keep as much precision as
  157. possible, the 40th bit of the double's significand is tested.  If
  158. the 40th bit is set, the significand's 39th bit is incremented. 
  159. If all of the first 40 bits of the double's significand are set,
  160. bits 1 to 39 are cleared and the exponent is incremented.  The
  161. exponent field is guaranteed not to be filled, so incrementing
  162. the exponent will succeed, because the function has already
  163. tested the exponent for its maximum value in checking whether the
  164. double's value was Inf or NaN.
  165.  
  166.      After rounding, the function places the value of the
  167. double's exponent in a variable and checks whether it fits within
  168. the range of valid real exponents.  Real exponents range from 1
  169. to 255 biased, or -128 to 126.  To fit in this range, the
  170. double's biased exponent must range from 895 to 1149.  If the
  171. double's exponent is less then 895, a real value of 0.0 and a
  172. code of prPosUnderflow or prNegUnderflow (depending on the
  173. double's sign) are returned.  If the double's exponent is greater
  174. than 1149, the real is set to its maximum value, the double's
  175. sign bit is transferred to the real, and a code of prOverflow is
  176. returned.
  177.  
  178.      After these checks, the function is assured of a valid
  179. conversion.  The exponent is re-biased for the real range, and it
  180. is transferred to the real along with the sign bit and the first
  181. 39 bits of the double's significand (which may have been
  182. rounded).  A code of prOK is then returned.
  183.  
  184.  
  185. BPRTEST Demonstration Program
  186.  
  187.      BPRTEST.C is a demonstration program that prompts the user
  188. for 6 values of type double, displaying each one, converting it
  189. to a real, displaying the conversion result code, and writing the
  190. real value to a file called BPREALS.DAT.  The program then reads
  191. the real values from the file, converting each real value to a
  192. double and displaying it.  Comparison of the original values with
  193. the values read from the file will show how double values are
  194. changed when they are converted to reals (real values never
  195. change when converted to doubles).
  196.  
  197.  
  198. Reference
  199.  
  200.      The information herein is derived from the Borland Pascal
  201. with Objects 7.0 Language Guide, Borland International 1992.
  202.  
  203.  
  204. Use and Distribution
  205.  
  206.      You may freely use and distribute BPREAL.C, BPRTEST.C, and
  207. BPREAL.DOC, but any distribution should include all 3 files
  208. together and intact.  Send questions or comments to the author,
  209. Richard Biffl, at 1024 N. Utah St. #618, Arlington, Virginia
  210. 22201, or on CompuServe at 73607,3043.
  211.          ----------------end-of-author's-documentation---------------
  212.  
  213.                          Software Library Information:
  214.  
  215.                     This disk copy provided as a service of
  216.  
  217.                            Public (software) Library
  218.  
  219.          We are not the authors of this program, nor are we associated
  220.          with the author in any way other than as a distributor of the
  221.          program in accordance with the author's terms of distribution.
  222.  
  223.          Please direct shareware payments and specific questions about
  224.          this program to the author of the program, whose name appears
  225.          elsewhere in  this documentation. If you have trouble getting
  226.          in touch with the author,  we will do whatever we can to help
  227.          you with your questions. All programs have been tested and do
  228.          run.  To report problems,  please use the form that is in the
  229.          file PROBLEM.DOC on many of our disks or in other written for-
  230.          mat with screen printouts, if possible.  PsL cannot debug pro-
  231.          programs over the telephone, though we can answer questions.
  232.  
  233.          Disks in the PsL are updated  monthly,  so if you did not get
  234.          this disk directly from the PsL, you should be aware that the
  235.          files in this set may no longer be the current versions. Also,
  236.          if you got this disk from another vendor and are having prob-
  237.          lems,  be aware that  some files may have become corrupted or
  238.          lost by that vendor. Get a current, working disk from PsL.
  239.  
  240.          For a copy of the latest monthly software library newsletter
  241.          and a list of the 4,000+ disks in the library, call or write
  242.  
  243.                            Public (software) Library
  244.                                  P.O.Box 35705
  245.                             Houston, TX 77235-5705
  246.  
  247.                                  Orders only:
  248.                                 1-800-2424-PSL
  249.                               MC/Visa/AmEx/Discover
  250.  
  251.                           Outside of U.S. or in Texas
  252.                           or for general information,
  253.                               Call 1-713-524-6394                 
  254.